/* Copyright (c) 1999, 2004, Oracle. All rights reserved.  */
/* All rights reserved */

This file is the README file for sample programs in the JPub demo
directory.  It specifies the steps required to run each of the
programs in this directory, and their expected behavior.
All demos use the scott/tiger schema.

0. First, check your environment setup
**************************************

0.1 Test the database setup: TestInstallCreateTable.java

    This JDBC program creates a table named 'SALES' in the 
    schema for user SCOTT. This table is used in the other 
    TestInstall program as well.

    The following commands will compile and run this program:

    % javac TestInstallCreateTable.java
    % java  TestInstallCreateTable

    Expected output on the screen is:

    SALES table created

    and the table should be present in the scott/tiger database account.  

    A related file is TestInstall.sql.  This file contains a SQL script 
    to create the same 'SALES' table via SQL*Plus.

0.2 Test the JDBC setup: TestInstallJDBC.java
    This is another program that verifies your JDBC setup.  
    It uses the SALES table created by the previous program, 
    TestInstallCreateTable.java, in user SCOTT's schema.

    The following commands will compile and run this sample:

    % javac TestInstallJDBC.java
    % java  TestInstallJDBC

    Expected output to the screen is:

    Hello JDBC!


0.3 Modify the entries in "connect.properties" and "jpub.properties"
    to reflect the logon strings used for your JDBC driver and database
    account.

    The demo programs in the demo directory use information contained
    in the file "connect.properties" to establish a runtime connection.
    In addition, the JPublisher utility uses information contained in
    the file "jpub.properties" to establish a connection.


0.4 Make sure the JPub utility can be invoked from the command line,
    and produces the expected output:

% jpub
JPub: Java Object Type Publisher, version 10.1.0.1.0 Production
Copyright (c) 1997, 2002, Oracle Corporation. All Rights Reserved.

JPub generates Java or SQLJ source code for the following SQL entities:
   object types, collection types, and packages.

Invocation:
   jpub <options>

The following option is required: 
   -user=<username>/<password>

Other options are:
   -input=<input file>
   Types and packages to be processed by JPub may be listed in the -input file
   The contents of the -input file may be as simple as:
      SQL Person
      SQL Employee

   -sql=<sql entity list>
   Types and packages to be processed by JPub may also be listed using the -sql option
   For example, -sql=a,b:c,d:e:f is equivalent to the -input file entries:
      SQL a
      SQL b AS c
      SQL d GENERATE e AS f

   The following options determine which Java types are generated
   to represent SQL user-defined, numeric, lob, and other types:
   -usertypes=oracle|jdbc
   -numbertypes=objectjdbc|jdbc|bigdecimal|oracle
   -lobtypes=oracle|jdbc
   -builtintypes=jdbc|oracle
   -addtypemap=<sql opaque type>:<java wrapper class>
   -addtypemap=<plsql type>:<java>:<sql type>:<sql2plsql>:<plsql2sql>
   -plsqlmap=true|false|always   - control generation of PL/SQL wrappers
   -plsqlfile=<file for generated PL/SQL wrapper code>
   -plsqlpackage=<package for generated PL/SQL code>

   -case=mixed|same|lower|upper
   -dir=<base directory for generated Java files>
   -driver=<JDBC-Driver>
      (default: oracle.jdbc.driver.OracleDriver)
   -encoding=<Java encoding of -input file and generated files>
   -gensubclass=true|force|call-super|false
   -methods=none|named|all
   -omit_schema_names
   -package=<package-name>
   -access=public|protected|package
   -compatible=ORAData|CustomDatum
   -context=generated|DefaultContext
   -serializable=true|false
   -tostring=true|false
   -props=<properties file from which to load options>
   -url=<JDBC-URL>
      (default: jdbc:oracle:oci8:@)


    If this expected output is not obtained, please check your environment
    settings for PATH and CLASSPATH:
       * PATH should include the directory ORACLE_HOME/bin
       * CLASSPATH should include the file ORACLE_HOME/sqlj/lib/translator.jar

    In addition, a JDK 1.2-compatible Java compiler (assumed to be javac)
    and the java interpreter (assumed java) must be correctly installed.

    If this expected output is not obtained, please check your environment
    settings, as described in section 0.2.


1. Next, run the sample programs in this directory.
***************************************************

Four rational number examples are provided, demonstrating three different
ways to do the same thing:

* "MyRationalC" uses a rational number object type.  The class JPub
  generates has no methods other than "get" and "set" accessor methods.
  The user extends the class JPub generates and adds additional methods.

The other examples involve client wrapper methods that invoke server-side
PL/SQL methods:

* "RationalO" uses a rational number object type, with a few methods for
  manipulating the rational numbers.

* "RationalP" puts the rational number methods in a PL/SQL package.  A
  rational number type without methods provides arguments to the PL/SQL
  methods in the package.

* "MyRationalO" shows another example of extending a JPub-generated
  rational number class.

* "MyRationalO8i" shows how to use the JPublisher 8i compatibility
  mode. This may be useful if you wrote an application with JPublisher
  version 8.1.7 or earlier, and do not want to change you application
  to take advantage of the changed APIs in JPublisher release 9i.


These examples are kept deliberately simple, so as not to obscure the
principles involved.

This directory contains the following files for demos 1.1 through 1.7.
Additional files are listed below with the demo that uses it.

  README.txt            the file you are now reading

  Rational.sql          SQL script to create the object types Rational and
                        RationalO and the PL/SQL package RationalP

  MyRationalC.java      Source code for the class MyRationalC

  TestMyRationalC.java  Test program to demonstrate use of the
                        class MyRationalC, a hand-written class that
                        extends the JPub-generated class JPubRationalC

  TestRationalO.java    Test program to demonstrate use of the class RationalO,
                        which JPub generates to represent the RationalO type

  TestRationalP.java    Test program to demonstrate use of the class RationalP,
                        which JPub generates to represent the PL/SQL package
                        RationalP. This test also uses the Rational class,
                        which JPub generates to represent the Rational type

  TestMyRationalO.java  Test program to demonstrate use of the class
                        MyRationalO, a hand-written class that extends the
                        JPub-generated class JPubRationalO.

  MyRationalO.java      Source code for the class MyRationalO

  MyRationalO8i.java    Source code for the class MyRationalO8i

  connect.properties    used by the test programs when they connect

  jpub.properties       used by JPub when it connects


1.1 Run the Rational.sql SQL script to create the object types and
    the PL/SQL package used in these examples. (replace scott/tiger
    with your username/password values).

    % sqlplus scott/tiger @Rational.sql

1.2 Run the MyRationalC test.  In this test, JPub generates
    JPubRationalC.java.
    This class represents the database object type RationalO.
    The hand-written class MyRationalC.java extends JPubRationalC
    by adding methods such as toString() and plus().

    % jpub -props=jpub.properties -sql=RationalO:JPubRationalC:MyRationalC -mapping=jdbc -methods=none
    % javac JPubRationalC.java MyRationalC.java TestMyRationalC.java
    % java TestMyRationalC
 
    The expected output is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1

1.3 Run the RationalO test.  In this test, JPub generates
    RationalO.java.  This class invokes server methods of the
    database object type RationalO, which represents rational numbers.

    % jpub -props=jpub.properties -sql=RationalO -methods=true
    % javac TestRationalO.java
    % java TestRationalO

    The expected output is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1

1.4 Run the RationalP test.  This time, JPub generates a .java file
    for the class Rational, which represents the database object type
    of the same name.
    This Rational class has numerator and denominator attributes, but
    no methods.
    JPub also generates a .java file for the Java class RationalP,
    which represents the PL/SQL package of the same name.
    This package has methods to manipulate rational numbers.

    % jpub -props=jpub.properties -sql=RationalP,Rational -mapping=oracle -methods=true
    % javac TestRationalP.java
    % java TestRationalP

    The expected output is:

    real value: 0.5
    gcd: 5
    sum: 100/100
    sum: 1/1

1.5 Run the MyRationalO test.  This test demonstrates how to extend a
    class generated by JPub.  This time, JPub generates
    JPubRationalO.java.  This class represents the database object
    type RationalO.  The hand-written class MyRationalO.java extends
    JPubRationalO by adding a toString() method.

    % jpub -props=jpub.properties -sql=RationalO:JPubRationalO:MyRationalO -methods=true
    % javac TestMyRationalO.java
    % java TestMyRationalO

    The expected output is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1


1.6 Run the MyRationalO8i test. This test is very similar to MyRationalO,
    except that JPublisher is run in 8i compatibility mode. In this mode
    JPublisher generates sources that will be compatible with code that
    you wrote for subclassing classes generated with JPublisher 8.1.7 or
    earlier.

    % jpub -props=jpub.properties -sql=RationalO:JPubRationalO8i:MyRationalO8i -methods=true -compatible=8i
    % jpub JPubRationalO8i.sqlj TestMyRationalO8i.java
    % java TestMyRationalO8i

    The second command above is to translate generated .sqlj program and the 
    .java test driver into .java and .class files. With SQLJ translate 
    desuppred, the command "jpub" provides an alternate access to SQLJ 
    translation facility. The expected output for the last command is:

    gcd: 5
    real value: 0.5
    sum: 100/100
    sum: 1/1

    Note that, with JDBC 10g releases, the second jpub command will show
    the following depracation message:

    Note: JPubRationalO8i.sqlj uses or overrides a deprecated API.  
    Recompile with "-deprecation" for details.
    1 warning

    The depracation message above is expected, because with -compatible=8i,
    JPublisher generates code using oracle.sql.CustomDatum APIs, which is
    depracated by JDBC 10g releases.


1.7 Run the inheritance test. This test shows how you can use JPublisher
    to generate code for a SQL object type inheritance hierarchy.
    The TestInh test driver is written in SQLJ and also shows the
    use of meta bind variable to write dynamic SQL code in SQLJ.
    
    First you need to create the types PERSON_T, STUDENT_T and
    GRADUATESTUDENT_T, as well as three associated extent tables in
    the database.

    % sqlplus scott/tiger @Inherit.sql

    Now you can use JPublisher to generate code, SQLJ to compile
    it and the test driver, and run it.

    % jpub -props=jpub.properties -sql=PERSON_T:InhPerson,STUDENT_T:InhStudent,GRADUATESTUDENT_T:InhGraduate
    % javac TestInh.java
    % java TestInh

    The expected output is:

    Insert InhPerson Jerry P. into PERSON_TAB
    Insert InhStudent George P. into PERSON_TAB
    Insert InhGraduate Robert P. into PERSON_TAB
    List the values selected from PERSON_TAB
    PERSON: 1002, Jerry P.
    STUDENT: 1202, George P., Chemistry
    GRADUATESTUDENT: 1222, Robert P., Biology, 30
    Insert InhStudent George S. into STUDENT_TAB
    Insert InhGraduate Robert S. into STUDENT_TAB
    List the values selected from STUDENT_TAB
    STUDENT: 1202, George S., Chemistry
    GRADUATESTUDENT: 1222, Robert S., Biology, 30
    Insert InhGraduate Robert G. into GRADUATESTUDENT_TAB
    List the values selected from GRADUATESTUDENT_TAB
    GRADUATESTUDENT: 1222, Robert G., Biology, 30


1.8 The next example creates a SQL object type BOOLEANS with object
    methods that use the PL/SQL type BOOLEAN.

    Source files:
      Booleans.sql
      TestBooleans.java.

    Generated files:
      Booleans.java
      BooleansWrap.sql

    Run the Booleans.sql SQL script to create the BOOLEAN type
    (replace scott/tiger with your username/password).
  
    % sqlplus scott/tiger @Booleans.sql

    Use JPublisher to publish the SQL object type BOOLEANS.
    Note that the JPublisher invocation below must be entered
    as a single command line.

    % jpub -props=jpub.properties -sql=BOOLEANS:Booleans \
           -plsqlfile=BooleansWrap.sql -plsqlpackage=BOOLEANS_WRAP \
           -tostring=true 
    % javac TestBooleans.java

    Run the SQL*Plus to load the generated PL/SQL wrapper
    code in the BOOLEANS_WRAP package.

    % sqlplus scott/tiger @BooleansWrap.sql

    Now run the test code.

    % java TestBooleans

    The expected output is:

    SCOTT.BOOLEANS(0,1,0).f(false) = true
    SCOTT.BOOLEANS(0,1,0).p(true,false -> true,-> true)
      returns new state SCOTT.BOOLEANS(0,null,0)


1.9 Run the index-by table demo. This demo shows JPub support for
    scalar index-by table types when using the JDBC-OCI driver.
    Some properties used for JPub are included in Indexby.sql,
    prefixed by "--  ".  They are used to set up typemap entries
    that map PL/SQL index-by table types to Java array types.

    Source files:
      Indexby.sql
      TestIndexby.java

    Generated files:
      Indexby.java

    First create the PL/SQL package INDEXBY with scalar
    index-by table types and procedures that use those types.

    % sqlplus scott/tiger @Indexby.sql

    Now publish this package to Java. Note that we have to specify
    the Indexby.sql script as a JPub properties files, since
    the type correspondences are defined there.

    % jpub -u scott/tiger -s Indexby -props=Indexby.sql 
    % javac TestIndexby.java

    Executing the test driver.

    % java TestIndexby

    The expected output is:

    Connected.
    getFloatAry() = [1.0,2.0,3.0,4.0,5.0]
    powIntegerAry([0,1,2,3,4,5,6], ->[0,1,4,9,16])
    xformVarcharAry([a,B,ce,day,aye] -> [a,B2B,ce3ce3ce,day4day4day4day,aye5aye5aye5aye5aye])
    Done.


1.10 Run the WrDbmsUtil demo. This test demonstrates the general 
     mechanism JPublisher uses to support PL/SQL types and packages. 
     The demo creates the necessary SQL types to publish a PL/SQL package 
     - here SYS.DBMS_UTIL - to Java. Note that the steps shown in this
     demo is mostly automatically performed by JPublisher, as shown in the 
     next demo. The purpse of the demo is to show how to support a PL/SQL
     or SQL type from scratch. 
    
    Source files: 
      WrDbmsUtil.sql   - creates supporting SQL types and conversions

    Generated files:
      WrDbmsUtil.java                  - actual wrapper for package
      WrDbmsUtilInstanceTable.java     - for supporting SQL type
      WrDbmsutilInstanceRecord.java    - for supporting SQL type
      WrDbmsutilInstanceRecordRef.java
      WrDbmsUtilPlsql.sql              - PL/SQL wrapper 

    First create SQL types that correspond to PL/SQL record
    types and to PL/SQL index-by table types, as well as PL/SQL
    conversion functions that map between the two.

    % sqlplus scott/tiger @WrDbmsUtil.sql

    Now invoke JPublisher and do two things at the same time:
     - publish the SQL types defined in WrDbmsUtil.sql
     - publish the package SYS.DBMS_UTILITY using the typemap
       entries and conversion functions we just defined.
    The typemap entries that map PL/SQL types from the
    DBMS_UTILITY package into these SQL types are embedded
    into the script as SQL comments.

    The following is a single JPublisher command line.

    % jpub -u scott/tiger -props=WrDbmsUtil.sql \
           -s SYS.DBMS_UTILITY:WrDbmsUtil

    Now load WR_DBMSUTIL_PLSQL into the database.

    % sqlplus scott/tiger @WrDbmsUtilPlsql.sql

    Now you can use the class WrDbmsUtil and the generated
    Java types to call functions and procedures in the
    SYS.DBMS_UTIL package.

1.11 Run the PlsqlType Demo. This test demonstrates JPublisher
     support for PL/SQL RECORD and TABLE. JPublisher can 
     automatically publish PL/SQL RECORD or TABLE types used
     in a PL/SQL stored procedure. JPublisher creates 
     corresponding SQL types and the conversion functions between
     the PL/SQL type and the SQL type. 
     
    Source files: 
      TestPlsqlType.java - Entry point of the demo, which invoke 
      the methods in the published classes
      PlsqlType.sql - PL/SQL package declaration 

    Generated files:
      PlsqlType.java - the published class  for the PL/SQL procedure
      plsql_wrapper.sql - SQL script creating the SQL types and 
                          conversion functions
      PlsqltypeEmpRec.java 
      PlsqltypeEmpRecRef.java 
      PlsqltypeEmpTbl.java
                        - Java classes generated for the SQL types

    (1) Create the PL/SQL package:

    % sqlplus scott/tiger @PlsqlType.sql

    (2) Publish the PL/SQL package:

    % jpub -u scott/tiger -s PlsqlType:PlsqlType -dir=plsqltype
    SCOTT.PLSQLTYPE
    SCOTT."PLSQLTYPE.EMP_REC"
    SCOTT."PLSQLTYPE.EMP_TBL"
    J2T-138, NOTE: Wrote PL/SQL package JPUB_PLSQL_WRAPPER to file plsqltype/plsql_wrapper.sql. Wrote the dropping script to file plsqltype/plsql_dropper.sql

    (3) Run the generated PL/SQL wrapper script
    % sqlplus scott/tiger @plsqltype/plsql_wrapper.sql

    (4) Run the client
    % cp TestPlsqlType.java plsqltype
    % cd plsqltype
    % javac TestPlsqlType.java 
    % java TestPlsqlType 

     getEmpRec returns Roy
     getEmpTbl returns 
       0, 2, Roy
       1, 3, Joe

    (5) Clean up the SQL type and conversion functions 
        created by the wrapper script  
    % sqlplus scott/tiger @plsqltype/plsql_dropper.sql
    (6) Clean up the PL/SQL package 
    sqlplus > drop package PlsqlType 

1.12 Run the Query and DML Demo. This test demonstrates that JPublisher
     can publish queries and DML statements into Java methods. 

     (1) Publish the query and DML statements
     % jpub -u scott/tiger -sqlstatement.class=Query -sqlstatement.return=both -dir=query -sqlstatement.getEmpBySal="select ename, sal, hiredate from emp where sal>:{mysal NUMBER}" -sqlstatement.getEmpCount="select count(*) as count from emp" -sqlstatement.insert="insert into emp (empno, ename, sal) values(:{myno NUMBER}, :{myname VARCHAR}, :{mysal NUMBER})" -sqlstatement.delete="delete from emp where ename='EMPTY'" -style=webservices-common
     (2) Run the query
     % cp TestQuery.java query
     % cd query
     % javac TestQuery.java 
     % java TestQuery

    (3) Expected Result: the TestQuery program returns the result 
    similar to the following.
      
     *** Query getEmpBySal ***" 
     SMITH, 800, 1980-12-17 00:00:00.0
     ALLEN, 1600, 1981-02-20 00:00:00.0
     WARD, 1250, 1981-02-22 00:00:00.0
     JONES, 2975, 1981-04-02 00:00:00.0
     MARTIN, 1250, 1981-09-28 00:00:00.0
     BLAKE, 2850, 1981-05-01 00:00:00.0
     CLARK, 2450, 1981-06-09 00:00:00.0
     SCOTT, 3000, 1987-04-19 00:00:00.0
     KING, 5000, 1981-11-17 00:00:00.0
     TURNER, 1500, 1981-09-08 00:00:00.0
     ADAMS, 1100, 1987-05-23 00:00:00.0
     JAMES, 950, 1981-12-03 00:00:00.0
     FORD, 3000, 1981-12-03 00:00:00.0
     MILLER, 1300, 1982-01-23 00:00:00.0
     *** Query getEmpCount ***
     14
     *** DML insert ***
     1
     *** DML batch insert ***
     -2
     *** Query getEmpCount ***
     17
     *** DML delete***
     0 
     *** Query getEmpCount ***
     17

For DML statement, a return value greater than zero usually 
means the number rows updated. A return value of -2 means 
an update is performed successfully as a batch execution. 
Other return values means the operation failed and the change 
is rolled back.

With the "-style=webservices-common" option, JPublisher will 
generate Java code conforming to webservices requirement, 
such as generating interfaces and converting types not supported 
by webservices into ones that are supported, e.g., converting 
java.util.Timestamp into java.util.Date. 

1.13 Run the Database Calllin Demo  (Demo 1). This test demonstrates 
     JPublisher support for database callin, i.e., calling Java 
     methods in the database server from a Java client outside 
     the database. The demo first publishes the 
     oracle.sqlj.checker.JdbcVersion class in the database server. 
     Then it invokes the methods in the published class, which returns
     JDBC version and SQLJ library information in the server.
     
    Source files: 
      TestCallin.java - Entry point of the demo, which invoke the methods
      in the published classes

    Generated files:
      Callin.java - the published class that invokes 
                    the server-side Java class 
      CallinImpl.java - interface of the published class 

    (1) The demo requires Database 10g Release 2.
    (2) Publish the oracle.sqlj.checker.JdbcVersion class 
    in the server:

    % jpub -u scott/tiger -java=oracle.sqlj.checker.JdbcVersion:CallinImpl#Callin
      Writing Callin.java
      Writing CallinImpl.java
    
    (3) Test the published classes:

    % javac TestCallin.java CallinImpl.java Callin.java
    % java TestCallin

    (4) Expected Result: the TestCallin program returns the result 
    similar to the following.
      
    Oracle JDBC driver version 10.2 (10.2.0.0.0)
    SQLJ runtime: Oracle 9.2.0 for JDBC SERVER/JDK 1.2.x - Built on Feb 08, 2005
    10.2.0.0.0
    Sqlj library: runtime12
    Oracle JDBC driver version 10.2 (10.2.0.0.0)
    SQLJ runtime: Oracle 9.2.0 for JDBC SERVER/JDK 1.2.x - Built on Feb 08, 2005

1.14 Run the Database Calllin Demo (Demo 2). The previous demo,
     Database Callin Demo (Demo 1), shows JPublisher support 
     for server-side Java invocation using the -java option. 
     A limitation of the -java option is that only serializable 
     parameter or return types are supported. Non-serializable 
     parameter or return types in a method will result in that 
     method not being published. An an alternative, JPublisher 
     provides another option, -dbjava, 
     to support JavaBeans and JDBC types. This demo simply echos 
     values of various types, including a JavaBean type, an ORAData
     type and a serializable type.
     
    Source files: 
      Callin2.java - Server-side Java class
      Callin2Bean.java - A JavaBean used in the Callin2 method 
                         signatures
      TestCallin2.java - Entry point of the demo, which invoke 
                         the methods in the published classes

    Generated files:
      Callin2JPub.java - server-side Java wrapper for the Callin2
      plsql_wrapper.sql - PL/SQL wrapper for the server-side Java class
      plsql_dropper.sql - PL/SQL script dropping the PL/SQL wrapper 
      Callin2Client.java - client-side Java class 

    (1) The demo requires Database 10g Release 2.
    (2) Load server-side Java classes
    % loadjava -u scott/tiger -r -v -f Callin2.java Callin2Bean.java
    
    (3) Publish ServerCallin02
    % jpub -u scott/tiger -sysuser=sys/change_on_install -dbjava=Callin2:Callin2Client -dir=tmp
    tmp/Callin2JPub.java
    tmp/plsql_wrapper.sql
    tmp/plsql_dropper.sql
    SCOTT.TBL_NUMBER
    SCOTT.TBL_TBL_NUMBER
    SCOTT.OBJ_CALLIN2BEAN
    SCOTT.TBL_OBJ_CALLIN2BEAN
    SCOTT.TBL_TBL_OBJ_CALLI
    SCOTT.JPUB_PLSQL_WRAPPER
    Executing tmp/plsql_dropper.sql
    Executing tmp/plsql_wrapper.sql
    Loading Callin2JPub.java 
    
    (4) Test the published classes:
    % javac -classpath tmp:${CLASSPATH} -d tmp TestCallin2.java
    % java -classpath tmp:${CLASSPATH} TestCallin2


    (5) Expected Result

      testInstNum() returned 1999
      testInstNum([]) returned 2999
      testCallin2Bean() returned mybean
      testCallin2Bean([]) returned mybean
      testSer() returned dean
      testSer([]) returned dean
      testSer([][]) returned dean

1.15 Run the SOAP-based Database WebService Callout demo. This test 
     demonstrates JPublisher support for accessing SOAP-based webservices 
     from inside the database via PL/SQL procedure or table function. 
     The webservice to be accessed provides weather information for 
     cities of given zipcodes. 
     
    Source file: 
      TemperatureService.wsdl - the WSDL file for the webservices 
      downloaded from 
        http://www.xmethods.net/sd/2001/TemperatureService.wsdl
    Requirement: 
      This demo requires a 10g database and also requires that 
      the weather serivce run on the internet with the endpoint 

        http://services.xmethods.net:80/soap/servlet/rpcrouter

      To verify wheather the service is available, access the URL 

        http://services.xmethods.net:80/soap/servlet/rpcrouter

      from the web browser. The return message should be

        SOAP RPC Router
        Sorry, I don't speak via HTTP GET- you have to use 
	HTTP POST to talk to me.

      The message above indicates that the service is available
      and one can proceed with this webservice callout demo. 

    (1) Prepare the Database
    (1.1) If the database is pre-9.2 database, run the following 
    command to load the necessary jar files into the SYS schema.

	  % loadjava -u sys/change_on_install -f -v -r -s -grant public activation.jar mail.jar http_client.jar xmlparserv2.jar soap.jar

    Those files to be loaded can be found in the 10g OC4J installation.

    (1.2) If the database is the 9.2 database, run the following command 
    to load the necessary jar files into the SYS schema. Ignore class 
    resolution errors with oracle.dms.* classes and possibly 
    oracle/security/ssl/OracleSSLCredential. 
	   . 
	   % loadjava -u sys/change_on_install -r -v -s -f -grant public \ 
	          ${J2EE_HOME}/lib/jssl-1_2.jar \ 
	          ${ORACLE_HOME}/soap/lib/soap.jar \ 
	          ${ORACLE_HOME}/dms/lib/dms.jar \ 
	          ${J2EE_HOME}/lib/servlet.jar \ 
	          ${J2EE_HOME}/lib/ejb.jar \ 
	          ${J2EE_HOME}/lib/mail.jar 

    Those files to be loaded can be found in the 10g OC4J installation.

    (1.3) If the database is 10g, run the command below to load 
    ORACLE_HOME/sqlj/lib/dbwsclient.jar into the SYS schema. 

      % loadjava -u sys/change_on_install -r -v -s -f -grant public
        dbwsclient.jar

    Refer to the note below for how to obtain dbwsclient.jar.

    (2) Make sure dbwsa.jar and JDBC, and SQLJ libraries are in
    the classpath. On Solaris, use the following command to set up 
    the classpath.

      % setenv CLASSPATH ${CLASSPATH}:${ORACLE_HOME}/sqlj/lib/dbwsa.jar:${ORACLE_HOME}/sqlj/lib/translator.jar:${ORACLE_HOME}/sqlj/lib/runtime12.jar:${ORACLE_HOME}/jdbc/lib/classes12.jar

    Note: The dbwsclient.jar and dbwsa.jar files are available 
          to be downloaded from OTN  
http://www.oracle.com/technology/sample_code/tech/java/jsp/dbwebservices.html 

    download: Database Webservices Callout Utilities [19-May-2004] 
              This sample demonstrates how to provide webservices access 
              from the database, typically, for PL/SQL clients. 
    Then, copy dbwsclient.jar and dbwsa.jar file to 
    ${ORACLE_HOME}/sqlj/lib/ directory. On NT, include dbwsa.jar file 
    in CLASSPATH.

    (3) Run JPublisher to generate WebServices client and its
    server-side wrappers. Then load the client and wrappers into
    the SCOTT schema. If you are not running inside a firewall,
    remove the -httpproxy option. Otherwise, adjust the -httpproxy
    setting to point to your http proxy host and port.

      % jpub -u scott/tiger -sysuser sys/change_on_install -proxywsdl=http://www.xmethods.net/sd/2001/TemperatureService.wsdl -httpproxy=www-proxy.us.oracle.com:80 -endpoint=http://services.xmethods.net:80/soap/servlet/rpcrouter -proxyopts=soap,tabfun -dir=weather -plsqlpackage=soap_callout_wrapper
      weather/TemperatureServiceProxyJPub.java
      weather/plsql_wrapper.sql
      weather/plsql_dropper.sql
      weather/plsql_grant.sql
      weather/plsql_revoke.sql
      Executing weather/plsql_wrapper.sql
      Executing weather/plsql_grant.sql
      Loading weather/plsql_proxy.jar

    (4) In SQLPLUS, run the PL/SQL wrapper method to get the temperature 
    for the zipcode 97229. 
      SQL>  conn scott/tiger  
      SQL>  select soap_callout_wrapper.gettemp('97229') from dual;

      SOAP_CALLOUT_WRAPPER.GETTEMP('97229')
      -----------------------------------
                                     50

    The output shows that the current temperature for Portland is 50 degree.

    (5) In SQLPLUS, run the PL/SQL table function to get the temperature 
    for a list cities specified by the zipcode table. 

      SQL> create table zipcodes(zip varchar2(5));
      SQL> insert into zipcodes values('97006');
      SQL> insert into zipcodes values('67003');
      SQL> insert into zipcodes values('19023');
      SQL> insert into zipcodes values('98271');
      SQL> insert into zipcodes values('83281');
      SQL> SELECT * FROM TABLE(SOAP_CALLOUT_WRAPPER.TO_TABLE_gettemp(CURSOR(SELECT * FROM zipcodes)));

      SQL> P0      RES
      SQL> ----------
      SQL> 97006   50
      SQL> 67003   63
      SQL> 19023   53
      SQL> 98271   48
      SQL> 83281   44

    The output shows that the temperature for the given zipcode cities are 
    50, 63, 53, etc.

1.16 Run the JAXRPC-based Database WebService Callout demo. This 
     test demonstrates JPublisher support for accessing webservices 
     from inside the database via PL/SQL procedure or table function. 
     The webservice to be accessed provides spelling check 
     among other features.  JPublisher generates and load JAXRPC 
     based webservices client, and then invokes that PL/SQL wrapper 
     generated and loaded for that client. 
     
     Requirement: 
      This demo requires a 10g database and also requires that 
      the WSDL file located at

        http://api.google.com/GoogleSearch.wsdl

      and associated service be available on the internet at 
      the time the demo is performed. 

    (1) Prepare the Database
      Download Database Webservice Callout Utilities 10.1.3 from 
      Oracle OTN download site 

      http://otn.oracle.com/sample_code/tech/java/jsp/dbwebservices.html

      Load dbwsclient.jar into the SYS schema. For example, 
      on Solaris, one can load that jar file using the command

      % loadjava -u sys/change_on_install -f -v -r -s -grant public 
        dbwsclient.jar

    Please refer to the note in previous sample about dbwsclient.jar.

    (2) Make sure dbwsa.jar and JDBC, and SQLJ libraries are in
    the classpath. On Solaris, use the following command to set up 
    the classpath.

      % setenv CLASSPATH ${CLASSPATH}:${ORACLE_HOME}/sqlj/lib/dbwsa.jar:${ORACLE_HOME}/sqlj/lib/translator.jar:${ORACLE_HOME}/sqlj/lib/runtime12.jar:${ORACLE_HOME}/jdbc/lib/classes12.jar

    Please refer to the note in previous sample about dbwsa.jar.

    (4) Make sure JDK used is 1.4 or later. Set PATH pointing to JDK 1.4 
    or later, if necessary.
    (5) Run JPublisher to generate WebServices client and its
    server-side wrappers. Then load the client and wrappers into
    the SCOTT schema. If you are not running inside a firewall,
    remove the -httpproxy option. Otherwise, adjust the -httpproxy
    setting to point to your http proxy host and port.

      % jpub -u scott/tiger -sysuser=scott/tiger -proxywsdl=http://api.google.com/GoogleSearch.wsdl -proxyopts=tabfun -httpproxy=www-proxy.us.oracle.com:80 -endpoint=http://api.google.com/search/beta2 -dir=tmp 
      
    (6) In SQLPLUS, run the PL/SQL wrapper method to correct a wrong 
        spelling. 
      SQL>  conn scott/tiger  
      SQL>  select jpub_plsql_wrapper.dospellingsuggestion(
              'qOFnPXFQFHLlXkyB4+D2nR870wLiNVhF',
              'workind') 
	    as doCheck 
	    from dual;

      DOCHECK
      -------
      working

    (7) In SQLPLUS, run the PL/SQL wrapper method to search for 
        "database webservices".  
      SQL>  conn scott/tiger  
      SQL>  select jpub_plsql_wrapper.doGoogleSearch(
            'qOFnPXFQFHLlXkyB4+D2nR870wLiNVhF',
            'database webservices', 
            0, 
            5,  
            1, 
            'j2ee', 
            1, 
            'lang_en', 
            'latin1', 
            'latin1') as dbws from dual;

     Expect a lenthy output.

1.17 Run the Advanced Queue Demo. This demo shows JPublisher 
     support for Oracle Stream Advanced Queue. We first create
     a queue of a SQL object type. Then, we run JPublisher to
     create a Java class that serves as the Java client to that
     queue. Finally, we excercise the published Java class by
     sending a message and receive a message throught that queue.
     
    Source files: 
      TestToyQueue.sql - Create a queue 
      TestToyQueue.java - A Java class calling JPublisher-generated
                       Java class. 
    Generated files:
      ToyQueue.java - The Java wrapper for that queue
      ToyType.java - The Java wrapper for the payload type of that queue

    (1) Create the queue 
      % sqlplus scott/tiger @TestToyQueue.sql
    (2) On Windows, ensure the following files are included in the classpath:
      %ORACLE_HOME%/rdbms/jlib/jmscommon.jar 
      %ORACLE_HOME%/rdbms/jlib/aqapi.jar
    (3) Publish that queue 
      % jpub -u scott/tiger  -sql=toy_queue:ToyQueue -dir=tmp1
    (4) Test the published classes:
      % javac -d tmp1 -classpath tmp1:$ORACLE_HOME/jlib/jndi.jar:${ORACLE_HOME}/rdbms/jlib/aqapi.jar:${ORACLE_HOME}/rdbms/jlib/jmscommon.jar:${CLASSPATH} TestToyQueue.java
      % java -classpath tmp1:$ORACLE_HOME/jlib/jndi.jar:${ORACLE_HOME}/rdbms/jlib/aqapi.jar:${ORACLE_HOME}/rdbms/jlib/jmscommon.jar:${ORACLE_HOME}/jlib/jta.jar:${CLASSPATH} TestToyQueue           

    (5) Expected Result
	Sent: banny rabbit - brown
	Sent: lego - 64 pieces
	Received: banny rabbit - brown
	Received: lego - 64 pieces

